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MUSIC FLAYER 


Program and Manual Contents 
Copyright (c) 1984 New Horizons Software 
All Rights Reserved 


This program falls under the Federal Copyright Law and may be used 
only by the purchaser for their own personal use. 


LIMITED WARRANTY ON MEDIA 


New Horizons Software warrants to the original purchaser that 
the media on which this computer program is recorded shall be free 
from defects in material or workmanship for a period of thirty (30) 
days from the date of purchase. 

This warranty shall not apply if the product has been damaged by 
accident* unreasonable use* or by other causes unrelated to defective 
materials or workmanship. 

This warranty gives you specific legal rights and you may also 
have other rights which vary from state to state. Some states do not 
allow limitations on how long an implied warranty lasts* and/or do 
not allow the exclusion of incidental or consequential damages* so 
the above limitations and exclusions may not apply to you. 

New Horizons Software designed this software for use on Atari 
computers. With proper application, this program will perform as 
promised in the manual. New Horizons Software* however* is 
responsible for neither the particular application nor any problems 
resulting from that input. 


We invite you to contact us with any questions, problems, or 
suggestions you might have concerning this software product. You 
may reach us at: 


New Horizons Software 
P.D. Box 180253 
Austin* Texas 78718 
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WHAT IS MUSIC FLAYER? 


Music Player is an easy to use utility that enables your programs 
to play songs you've created with Atari's Music Composer <tm) 
cartridge. With Music Player you have the added ability to stop and 
re-start the music at any point* and speed up or slow down the music 
as it plays. Best of all, Music Player works at the same time as your 
program - your music will play while your program keeps running. 
You can even have music playing while you edit your program! 

With Music Player you can create musical teaching programs, 
guessing games, or simply provide a musical interlude while your 
program performs a lengthy operation. 

You can use Music Player with BASIC, Assembly, and other 
languages that allow AUTORUN.SYS files and OPEN, CLOSE, and PUT 
statements (or similar statements). 


We at New Horizons Software recognize that you may wish to 
distribute programs which incorporate Music Player. Please contact 
us for further information if you wish to use Music Player for this 
purpose. We welcome all questions and comments regarding Music 
Player. Our address is given in the front of this manual. 
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STARTING OUT 


MAKING A COPY OF MUSIC PLAYER 

Before you use Music Player* it is a good idea to make a backup 
copy and always use this instead of your original. That way if 
something happens to your copy* you will always have the original to 
fall back on. To make a copy* simply follow the instructions on 
duplicating disks in your DOS reference manual. 

After you make this copy* you should create a MEM.SAV file on 
the diskette. This will let you switch back and forth between DOS 
and BASIC without having to re-load Music Player. See the 
discussion on Warnings in the ERROR CONDITIONS section. 


LOADING MUSIC PLAYER 

To load Music Player for use with BASIC* you must: 

1. Turn on your disk drive 

2. Insert the Music Player diskette 

3. Insert the BASIC cartridge 

4. Turn on your computer 

You will see a message telling you Music Player is loading* followed 
by a READY prompt. Music Player is now in your computer and ready 
for your use. 
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USING MUSIC PLAYER ‘WITH 
BASIC 


OVERVIEW 

There are three steps to using Music Player: 

1. Loading the Music Composer song file. 

2. Setting up Music Player to play the song. 

3. Playing the song. 

To illustrate the use of Music Player, we will create a program 
step-by-step that will play the song contained in the Music Composer 
file "D-.AMERICA.MUS” (This song file is present on the Music Player 
disk). 


LOADING THE SONG FILE 

The first step is to load the song file. Music Player has set aside 
an area of memory to hold the information. This area is 2000 bytes 
long and starts at location 8800 (decimal). A typical program section 
that will load the song is: 

100 OPEN #1,4,0,"D:AMERICA.MUS M 

110 TRAP 180 

120 FOR 1=0 TO 1999 

130 GET Ml,BYTE 

140 POKE 8800+I,BYTE 

150 NEXT I 

160 PRINT "SONG FILE IS TOO BIG!!" 

170 END 
180 POP 
190 CLOSE Ml 

Notice if the song file is larger than 2000 bytes this program section 
will display an error message and stop (of course you could have it do 
something different). If 2000 bytes is too small for your songs, you 
can modify Music Player to give it a larger song holding area — see 
the section on CUSTOMIZING MUSIC PLAYER. 

Because of the slowness when using GET and POKE, loading a 
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song file by this method can be very time consuming. Fortunately* 
Music Player provides an easier way. Included with Music Player is a 
machine-language routine for loading song files from disk.. Using 
this routine is very simple* a program section equivalent to the 
previous one is: 

100 OPEN #1,4,0,"DsAMERICA.MUS" 

110 OK=USR<870Q , 1) 

120 IF NOT OK THEN PRINT "SONG FILE IS 
TOO BIG!!":END 
130 CLOSE #1 

Your program calls the load routine from BASIC with the USR 
function. The first value in the USR function is the location of the 
routine* and is always 8700 (decimal). The second value is the unit 
number from the OPEN statement. Since we opened unit #1 in line 
100* we must use this number when calling the load routine. If for 
example you chose to use unit #2 instead* then your- program section 
will look like: 

100 OPEN #2,4,0,"DsAMERICA.MUS" 

110 OK=USR< 8700,2) 

120 IF NOT OK THEN PRINT "SONG FILE IS 
TOO BIG!!"SEND 
130 CLOSE #2 

and so on. The load routine returns a value of zero if there was no 
error during the load, and a value of 1 if there was. Line 120 checks 
for this and stops the program if an error occurred. This program 
section assumes all errors are caused by the file being too big for 
Music Player* since this is the most likely cause. 


SETTING UP MUSIC PLAYER 

Now that you have loaded the song* we need to tell Music Player 
the song information is there. You do this by simply using the OPEN 
statement: 

200 OPEN #1,8,0,"M:" 

That's all there is to it! The "M:" in the OPEN specifies Music 
Player, and you open for output since you will shortly be giving 
commands to Music Player with the PUT command. Music Player will 
check over the song file you have just loaded to make sure it has all 
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the information it needs to play the song. Music Player may 
encounter errors while checking the song (such as missing some part 
of the file)* and you can use the TRAP statement to detect these 
errors just like any other BASIC error. See the section on ERRORS 
CONDITIONS for more information. 


PLAYING YOUR SONG 

All that remains is to play the song. To do this you simply use 
the PUT statement to give Music Player a "Play" command: 

210 PUT #1,ASC<"P") 

The "P" is the command for Music Player to play the song from the 
start. Be sure the unit number (here a #1) is the same as the one 
from the OPEN statement. 

There are several other commands Music Player understands. 
Here is a complete list: 

P - Play 

Play the song from the beginning 
H -Halt 

Stop playing the song until the next Play or Resume command 
R - Resume 

Start playing the song from the point last Halted 
F - Fast 

Speed up the song's tempo 
S - Slow 

Slow down the song's tempo 

The Fast and Slow commands change the tempo value which was saved 
with the song file. The tempo can range from a low of one (fastest) 
to a high of 255 (slowest)* but any value greater than nine is probably 
too slow to be useful (Music Composer will only let you specify 
values from one to nine). See the Music Composer manual for more 
information. 
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FINAL TOUCHES 


Finally to complete your- program, you can let the user- give any 
one o-f the above commands to Music Player. This program section 
will do this (although it is not necessarily the best way): 

220 OPEN M2,4,0,"K:" 

230 PRINT "P, H, R, F, S, E ->"; 

240 GET M2,KEY 
250 PRINT CHR*<KEY> 

260 IF KEY=ASC<"P"> OR KEY=ASC<"H") OR 

KEY=ASC<"R") OR KEY=ASC("F") OR 

KEY=ASC( 11 S" ) THEN PUT Ml, KEY-.GOTO 230 

270 IF KEYOASC< " E") THEN 230 

280 CLOSE M2 

290 CLOSE Ml 

300 END 

To completely stop a song and prepare to load a new one, use the 
CLOSE statement as in line 290 of this program section. 


THE END RESULT 


Your complete program to load and play the song file 
n D: A MERIC A .MUS" now looks like: 

100 OPEN Ml ,4,0,"D:AMERICA.MUS" 

110 OK=USR(8700,1) 

120 IF NOT OK THEN PRINT "SONG FILE IS 
TOO BIG!!";END 
130 CLOSE Ml 
200 OPEN Ml,8,0,"Ms" 

210 PUT Ml ,ASC<"P") 

220 OPEN M2,4,0,"K s" 

230 PRINT "P, H, R, F, S, E 

240 GET M2,KEY 

250 PRINT CHR*<KEY> 

260 IF KEY=ASC<"P") OR KEY=ASC<“H") OR 

KEY=ASC<“R") OR KEY=ASC("F") OR 

KEY=ASC<"S"> THEN PUT M 1,KEYsGOTO 230 

270 IF KEYOASC< "E"> THEN 230 

280 CLOSE M2 

290 CLOSE Ml 

300 END 
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SUMMARY 


Summarizing, to use Music Player you -first load the song file: 

OPEN #1,4,0,"D:AMERICA.MUS" 

QK=USR< 8700,1) 

CLOSE #1 

Then setup Music Player; 

OPEN # 1,8,0 , " M : " 

Then play the song; 

PUT #1,ASC<"P"> 

To give Music Player other commands, such as "H" (Halt), "R" 
(Resume), "F" (Fast), or "S" (Slow), simply use that command character 
in place of the "P" used above. 

When you finish with the song, simply CLOSE Music Player: 

CLOSE #1 

And that's all there is to it. Using these steps you can even play 
music while you are editing a program! 
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USING MUSIC PLAYER WITH 
OTHER LANGUAGES 


To be able to use Music Player with other languages, the language 
must boot AUTORUN.SYS-files from disk., must not use the memory 
space used by Music Player (from the top of DOS to the end of the 
song buffer at decimal location 9000), and must use BASIC style I/O 
operations (specifically, OPEN, PUT, and CLOSE). 

To use Music Player with such a language, you simply perform the 
same operations as in the example from the previous section, namely- 

1. Load the song file into Music Player's song buffer. 

2. Initialize Music Player by issuing an OPEN-type statement to the 
"M:" device. 


3. Give Play, Halt, Resume, Fast, and Slow commands to Music Player 
with the PUT-type statement. 

4. Stop the song playing by issuing a CLOSE-type statement. 

Y ou must not use the fast load routine (at decimal location 8700) 
unless the language supports BASIC-style parameter passing to 
machine language routines. 

If you are in doubt as to whether the language you chose can use 
Music Player, please contact us. We will try our best to help you. 
Our address is given in the front of this manual. 
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CUSTOMIZING MUSIC PLAYER 


INCREASING THE BUFFER SIZE 

The first step in using Music player is loading the song file into 
Music Player's buffer. This buffer starts at (decimal) location 8800 
(this number was chosen for ease in remembering), and the default 
buffer size is 2000 bytes. This size has been found to be large 
enough for all but very large Music Composer song files. However, if 
you discover that you need a larger buffer size you can increase it (up 
to a maximum of 10,000 bytes) by using the buffer modification 
program supplied with Music Player. Make sure you use this program 
on a copy of Music Player, since it permanently changes the buffer- 
size of that copy. To use this program, insert your Music Player 
diskette and type: 

RUN "D:BUFFER" 

Follow the directions given on the screen to modify your copy of 
Music Player so that it will always use your buffer size. 


AUTORUNNING A BASIC PROGRAM 

Often times you might wish to use Music Player with programs for 
young children, or others who are not familiar with computers. In 
such cases it would be nice if your program would automatically start 
up when you first turn your computer on. Music Player allows you to 
do Just that. 

Included on your Music Player diskette is a program which will 
modify Music Player to automatically load and run any BASIC program 
you wish. Again, make sure that you do this only to a copy of Music 
Player, as the modification is permanent to that copy. 

To use this program, insert your Music Player diskette and type: 

RUN "D:AUTOMATE" 

Follow the directions given on the screen to modify Music Player to 
automatically run your BASIC program when the computer is first 
turned on. 
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ERROR CONDITIONS 


OPEN ERRORS 

Music Player- can encounter- several possible errors when it tries 
to per-form the OPEN statement. These errors occur just like any 
other Atari BASIC error, and you can use the TRAP statement to 
catch them should they occur. The error numbers generated by Music 
Player start at 200 to avoid con-flict with other Atari I/O error- 
numbers. An explanation of each type of possible error is as follows: 

200 - PLAY IS ACTIVE 

You've attempted to OPEN or re-OPEN a song file, but you 
haven't properly CLOSEd the one that was previously 
OPENed. You can have only one song file open at a time. 

201 - INCORRECT FILE STRUCTURE 

A data record (Phrase, Voice, Misc, or bad data) has been 
found that doesn't start with the correct header byte of 170. 
All data records in the song file must have the proper header- 
byte before they can be processed. 

202 - NO PHRASE RECORD FOUND 

The song file has no Phrase records. All song files must have 
at least one Phrase record. You might not have specified to 
Music Composer that you wanted to save everything when you 
saved the song file. 

203 - NO VOICE RECORD FOUND 

The song file has no Voice records. All song files must have 
at least one Voice record. You might not have specified to 
Music Composer that you wanted to save everything when you 
saved the song file. 

204 - NO MISC RECORD FOUND 

The song file has no Misc record. All song files must have a 
Misc record. You might not have specified to Music Composer 
that you wanted to save everything when you saved the song 
file. 
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Refer to the Music Composer user's manual for more information 
on the data record structure within a song file. 


WARNINGS 

Just as with BASIC's SOUND statement, you must not perform any 
input or output operations to peripheral devices (like the disk drive, 
program recorder, or printer) while Music Player is playing. To 
perform such I/O, either Halt or End the music being played. 

If you wish to be able to go from BASIC to DOS and back again, 
and still be able to use Music Player, then you must have a MEM.SAV 
file on your Music Player diskette. If you do not, then when you go 
to DOS, Music Player will be destroyed. Any attempt to use Music 
Player after that will lead to a total system lock-up, with the only 
remedy being to turn your computer off and on again. 
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H>E3MOKtSTR-A.TI O2M PROGRAM 


Your Music Player- diskette contains a demonstration program in 
BASIC* and ii song -files to go with it. The songs included are: 

1 - Ode to Joy 

2 - La Donna e Mobile 

3 - Bourree 

4 - The Barber of Seville 

5 - The Emperor Waltz 

6 - Amazing Grace 

7 - Dixie 

8 - Greensleeves 

9 - Shenandoah 

10 - When Johnny Comes Marching Home Again 

11 - America the Beautiful 

To try the program* first make sure you have loaded Music Player* 
then insert your Music Player diskette and type 

RUN "D:PLAYER" 

Y ou will be presented with a menu which lists the above songs. 
Follow the directions given on the screen and enjoy! 
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QUICK REFERENCE 


FILES ON DISKETTE 

The following -files are contained on your- Music Player diskette: 

AUTORUN.SYS - Music Player program 

DEMO - BASIC demo program from this manual 

BUFFER - BASIC program to change Music Player's buffer size 

AUTOMATE - BASIC program to make Music Player auto-run a 
program 

PLAYER - Demonstration BASIC program 
*.MUS - Song files (11) 


USING MUSIC PLAYER 

The song file must first be loaded into the Music Player buffer 
which starts at (decimal) location 8800* and is 2000 bytes long. A 
load routine is provided which will perform this load operation. To 
use it you must first OPEN the song file for input* then perform: 

X=USR(3700,iocb_no) 

where iocb_no is the IOCB number from the OPEN statement. You 
then must CLOSE the file. If the returned value (X in the above 
example) is one (1) then the load was ok* if it is zero (0) then there 
was an error. 

After loading the song file* you must initialize Music Player. This 
is done by OPENing the "M:" device for output* for example: 

OPEN #1,8,0,"M:" 

Music Player may encounter an error when initializing, see the 
ERROR CONDITIONS section for more information. 

Once you have set up Music Player, you control the playing of your 
song with the PUT statement. Y ou use the PUT statement to give 
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Music Player a single character command for the operation you wish. 
For example* the following will start playing the song: 

PUT #l t ASC<"P"> 

The commands which Music Player recognizes are: 

P - Play the song from the beginning 

H - Halt the song until a P or R command 

R - Resume playing from the point halted 

F - Fast; speed up the song's tempo 

S - Slow; slow down the song's tempo 

To stop the song completely and prepare for another song, simply 
CLOSE the device: 

CLOSE #1 

Of course you can only have one song active at a timet so be sure to 
CLOSE Music Player before you load a new song file. 
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